<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>HTTP Authentication Adapter - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.auth.adapter.http.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.auth.adapter.http.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.auth.adapter.digest.html">Digest Authentication</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.auth.html">Zend_Auth</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.auth.adapter.ldap.html">LDAP Authentication</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.auth.adapter.http" class="section"><div class="info"><h1 class="title">HTTP Authentication Adapter</h1></div>
    

    <div class="section" id="zend.auth.adapter.http.introduction"><div class="info"><h1 class="title">Introduction</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Auth_Adapter_Http</span> provides a mostly-compliant
            implementation of <a href="http://tools.ietf.org/html/rfc2617" class="link external">&raquo; RFC-2617</a>,
            <a href="http://en.wikipedia.org/wiki/Basic_authentication_scheme" class="link external">&raquo; Basic</a>
            and <a href="http://en.wikipedia.org/wiki/Digest_access_authentication" class="link external">&raquo; Digest</a>
            <acronym class="acronym">HTTP</acronym> Authentication. Digest authentication is a method of
            <acronym class="acronym">HTTP</acronym> authentication that improves upon Basic authentication by
            providing a way to authenticate without having to transmit the password in clear text
            across the network.
        </p>

        <p class="para">
            <em class="emphasis">Major Features:</em>
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    Supports both Basic and Digest authentication.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Issues challenges in all supported schemes, so client can respond with any
                    scheme it supports.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Supports proxy authentication.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Includes support for authenticating against text files and provides an
                    interface for authenticating against other sources, such as databases.
                </p>
            </li>
        </ul>

        <p class="para">
            There are a few notable features of <acronym class="acronym">RFC-2617</acronym> that are not
            implemented yet:
        </p>

        <ul class="itemizedlist">
            <li class="listitem">
                <p class="para">
                    Nonce tracking, which would allow for &quot;stale&quot; support, and increased replay
                    attack protection.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Authentication with integrity checking, or &quot;auth-int&quot;.
                </p>
            </li>

            <li class="listitem">
                <p class="para">
                    Authentication-Info <acronym class="acronym">HTTP</acronym> header.
                </p>
            </li>
        </ul>
    </div>

    <div class="section" id="zend.auth.adapter.design_overview"><div class="info"><h1 class="title">Design Overview</h1></div>
        

        <p class="para">
            This adapter consists of two sub-components, the <acronym class="acronym">HTTP</acronym> authentication
            class itself, and the so-called &quot;Resolvers.&quot; The <acronym class="acronym">HTTP</acronym> authentication
            class encapsulates the logic for carrying out both Basic and Digest authentication. It
            uses a Resolver to look up a client&#039;s identity in some data store (text file by
            default), and retrieve the credentials from the data store. The &quot;resolved&quot; credentials
            are then compared to the values submitted by the client to determine whether
            authentication is successful.
        </p>
    </div>

    <div class="section" id="zend.auth.adapter.configuration_options"><div class="info"><h1 class="title">Configuration Options</h1></div>
        

        <p class="para">
            The <span class="classname">Zend_Auth_Adapter_Http</span> class requires a configuration array
            passed to its constructor. There are several configuration options available, and some
            are required:
        </p>

        <table id="zend.auth.adapter.configuration_options.table" class="doctable table"><div class="info"><caption><b>Configuration Options</b></caption></div>
            

            
                <thead valign="middle">
                    <tr valign="middle">
                        <th>Option Name</th>
                        <th>Required</th>
                        <th>Description</th>
                    </tr>

                </thead>


                <tbody valign="middle" class="tbody">
                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">accept_schemes</span></em></td>
                        <td align="left">Yes</td>

                        <td align="left">
                            Determines which authentication schemes the adapter will accept from
                            the client. Must be a space-separated list containing
                            <em class="emphasis">&#039;basic&#039;</em> and/or <em class="emphasis">&#039;digest&#039;</em>.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">realm</span></em></td>
                        <td align="left">Yes</td>

                        <td align="left">
                            Sets the authentication realm; usernames should be unique within a
                            given realm.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">digest_domains</span></em></td>

                        <td align="left">
                            Yes, when <span class="property">accept_schemes</span> contains
                            <em class="emphasis">digest</em>
                        </td>

                        <td align="left">
                            Space-separated list of <acronym class="acronym">URI</acronym>s for which the same
                            authentication information is valid. The <acronym class="acronym">URI</acronym>s need
                            not all point to the same server.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">nonce_timeout</span></em></td>

                        <td align="left">
                            Yes, when <span class="property">accept_schemes</span> contains
                            <em class="emphasis">digest</em>
                        </td>

                        <td align="left">
                            Sets the number of seconds for which the nonce is valid. See notes
                            below.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">proxy_auth</span></em></td>
                        <td align="left">No</td>

                        <td align="left">
                            Disabled by default. Enable to perform Proxy authentication, instead
                            of normal origin server authentication.
                        </td>
                    </tr>

                </tbody>
            
        </table>


        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                The current implementation of the <span class="property">nonce_timeout</span> has some
                interesting side effects. This setting is supposed to determine the valid lifetime
                of a given nonce, or effectively how long a client&#039;s authentication information is
                accepted. Currently, if it&#039;s set to 3600 (for example), it will cause the adapter
                to prompt the client for new credentials every hour, on the hour. This will be
                resolved in a future release, once nonce tracking and stale support are
                implemented.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.auth.adapter.http.resolvers"><div class="info"><h1 class="title">Resolvers</h1></div>
        

        <p class="para">
            The resolver&#039;s job is to take a username and realm, and return some kind of credential
            value. Basic authentication expects to receive the Base64 encoded version of the user&#039;s
            password. Digest authentication expects to receive a hash of the user&#039;s username, the
            realm, and their password (each separated by colons). Currently, the only supported
            hash algorithm is <acronym class="acronym">MD5</acronym>.
        </p>

        <p class="para">
            <span class="classname">Zend_Auth_Adapter_Http</span> relies on objects implementing
            <span class="classname">Zend_Auth_Adapter_Http_Resolver_Interface</span>. A text file resolver
            class is included with this adapter, but any other kind of resolver can be created
            simply by implementing the resolver interface.
        </p>

        <div class="section" id="zend.auth.adapter.http.resolvers.file"><div class="info"><h1 class="title">File Resolver</h1></div>
            

            <p class="para">
                The file resolver is a very simple class. It has a single property specifying a
                filename, which can also be passed to the constructor. Its
                 <span class="methodname">resolve()</span> method walks through the text file, searching
                for a line with a matching username and realm. The text file format similar to
                Apache htpasswd files:
            </p>

            <pre class="programlisting brush: txt">
&lt;username&gt;:&lt;realm&gt;:&lt;credentials&gt;\n
</pre>


            <p class="para">
                Each line consists of three fields - username, realm, and credentials - each
                separated by a colon. The credentials field is opaque to the file resolver; it
                simply returns that value as-is to the caller. Therefore, this same file format
                serves both Basic and Digest authentication. In Basic authentication, the
                credentials field should be written in clear text. In Digest authentication, it
                should be the <acronym class="acronym">MD5</acronym> hash described above.
            </p>

            <p class="para">
                There are two equally easy ways to create a File resolver:
            </p>

            <pre class="programlisting brush: php">
$path     = &#039;files/passwd.txt&#039;;
$resolver = new Zend_Auth_Adapter_Http_Resolver_File($path);
</pre>


            <p class="para">
                or
            </p>

            <pre class="programlisting brush: php">
$path     = &#039;files/passwd.txt&#039;;
$resolver = new Zend_Auth_Adapter_Http_Resolver_File();
$resolver-&gt;setFile($path);
</pre>


            <p class="para">
                If the given path is empty or not readable, an exception is thrown.
            </p>
        </div>
    </div>

    <div class="section" id="zend.auth.adapter.http.basic_usage"><div class="info"><h1 class="title">Basic Usage</h1></div>
        

        <p class="para">
            First, set up an array with the required configuration values:
        </p>

        <pre class="programlisting brush: php">
$config = array(
    &#039;accept_schemes&#039; =&gt; &#039;basic digest&#039;,
    &#039;realm&#039;          =&gt; &#039;My Web Site&#039;,
    &#039;digest_domains&#039; =&gt; &#039;/members_only /my_account&#039;,
    &#039;nonce_timeout&#039;  =&gt; 3600,
);
</pre>


        <p class="para">
            This array will cause the adapter to accept either Basic or Digest authentication, and
            will require authenticated access to all the areas of the site under
            <var class="filename">/members_only</var> and <var class="filename">/my_account</var>. The realm
            value is usually displayed by the browser in the password dialog box. The
            <span class="property">nonce_timeout</span>, of course, behaves as described above.
        </p>

        <p class="para">
            Next, create the <span class="classname">Zend_Auth_Adapter_Http</span> object:
        </p>

        <pre class="programlisting brush: php">
$adapter = new Zend_Auth_Adapter_Http($config);
</pre>


        <p class="para">
            Since we&#039;re supporting both Basic and Digest authentication, we need two different
            resolver objects. Note that this could just as easily be two different classes:
        </p>

        <pre class="programlisting brush: php">
$basicResolver = new Zend_Auth_Adapter_Http_Resolver_File();
$basicResolver-&gt;setFile(&#039;files/basicPasswd.txt&#039;);

$digestResolver = new Zend_Auth_Adapter_Http_Resolver_File();
$digestResolver-&gt;setFile(&#039;files/digestPasswd.txt&#039;);

$adapter-&gt;setBasicResolver($basicResolver);
$adapter-&gt;setDigestResolver($digestResolver);
</pre>


        <p class="para">
            Finally, we perform the authentication. The adapter needs a reference to both the
            Request and Response objects in order to do its job:
        </p>

        <pre class="programlisting brush: php">
assert($request instanceof Zend_Controller_Request_Http);
assert($response instanceof Zend_Controller_Response_Http);

$adapter-&gt;setRequest($request);
$adapter-&gt;setResponse($response);

$result = $adapter-&gt;authenticate();
if (!$result-&gt;isValid()) {
    // Bad userame/password, or canceled password prompt
}
</pre>

    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.auth.adapter.digest.html">Digest Authentication</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.auth.html">Zend_Auth</a></span><br />
                        <span class="home"><a href="manual.html">Programmer's Reference Guide</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.auth.adapter.ldap.html">LDAP Authentication</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="manual.html">Programmer's Reference Guide</a></li>
  <li class="header up"><a href="reference.html">Zend Framework Reference</a></li>
  <li class="header up"><a href="zend.auth.html">Zend_Auth</a></li>
  <li><a href="zend.auth.introduction.html">Introduction</a></li>
  <li><a href="zend.auth.adapter.dbtable.html">Database Table Authentication</a></li>
  <li><a href="zend.auth.adapter.digest.html">Digest Authentication</a></li>
  <li class="active"><a href="zend.auth.adapter.http.html">HTTP Authentication Adapter</a></li>
  <li><a href="zend.auth.adapter.ldap.html">LDAP Authentication</a></li>
  <li><a href="zend.auth.adapter.openid.html">Open ID Authentication</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>